CATcoverage API from Poulton Associates

New Business Application Workflow

This page presents the basic workflow of a new business application.

This page focuses on the most stream-lined path from creating a new business application and getting a price indication through submitting it for underwriter approval and checking the status.
Some methods from the Swagger UI definition may not be included on this page.
You can view the complete list of available methods on the Swagger UI page and experiment calling them on our demo site.
Please contact our support if there are methods you would like to have documented in more detail.

Prerequisites

Before you start this walk-through:

  • Install Postman
    • This can be downloaded at: https://www.postman.com/downloads/
      • You don't need to sign in or create an account.
        • Just look for the alternate options to skip sign-in when prompted (it can be really small and inconspicuous).
  • Open Postman and import our example collection that accompanies this walk-through.
    • Download our Postman collection
    • Open Postman (skip the sign-in, or sign in with your account), click the "Import" button at the top-left of the window and select the collection file just downloaded.
    • After importing, you should see the "CATcoverage API v2 - New Biz" collection in the list at the left.
  • Obtain a client ID and secret.
    • The Postman example requests automatically fetch a client access token as necessary for authorization.
    • The "Variables" tab in the collection has variables for clientId and clientSecret that must be filled in or else the requests will all return with 401 (unauthorized) responses.

Step 1 - Get a price indication

Allows submitting a property address along with basic risk information to get a price indication in a single request.
If necessary, subsequent price-indication requests can be made to update an existing new business application and get an updated price indication result.
All premium indications given for applications in the works are subject to change until approved by an underwriter. No coverage is granted until payment of premium is received in full after underwriter approval.

There are 2 price indication methods, for personal lines and commercial lines risks. Choose the method that applies for your situation.

Commercial lines - Create a new business application and get a price indication.

  • In the Postman collection, open the request named "Get Price Indication - COMM - new app".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
    • Depending on the risk data entered, this response can take between about 15 to 60 seconds to return.
      • This may seem slow, but we're running several 3rd-party data collection and rate/premium calculation methods on the backend call to give you the best possible price through our insurers for the given risk.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data that includes the following items of special interest:
    • ApplicationId - used to identify this application in later API requests and responses
    • cost
      • totalCost - the resulting total cost to obtain a policy (premium plus any fees or taxes)
      • lineItems - the list of line items that make up the totalCost (premium, each fee, each tax)
    • status.status
      • statusCode - identifies the current status of the overall new business application
      • statusMessage - identifies any reasons provided for the current status (for example, if the premium could not be calculated this will contain the general reason why)
    • status.eligibility
      • isEligible - false when the given risk cannot be accepted by any of our several product offerings, or if eligibility could not be determined because risk data is not yet complete enough
      • problems - if isEligible is false, a list of any problems describing why eligibility hasn't passed
    • status.sections - identifies the specific status for each section of information in the application, along with any message related to that status

Commercial price indication - request description

  • risks - contains a list of buildings with information identifying the risk data, address, and limits to be insured.
    • buildingData
      • buildingDescription is required and should be unique for all buildings in the same application.
      • floodZone can be specified to match a flood zone determination result from a mortgagee requiring flood insurance.
      • buildingReplacementCostValue should be provided to ensure it is accurate.
        • This is different than the limit of insurance for the building, provided by limits.building.
      • All other properties here are optional and we will attempt to auto-fill them.
        • If we can't fill in a value, the result will include a message identifying what must be provided to obtain a price indication.
        • To get a list of the values allowed for these properties, see our new business application support methods page.
    • address
      • address contains the physical location of the building. It cannot be a PO Box or mailing address different than the physical location of the property to be insured.
      • copyToMailingAddress can be set to true if the same address can be used for the insured's mailing address for CATcoverage correspondence.
      • limits - the requested limits of insurance for the building.
      • Note that the buildingData.buildingReplacementCostValue is different than this building limit.
  • perilsDeductibles - contains the perils selected to be insured for this risk.
    • At least one peril must be selected.
    • The deductibleCode value must be provided for the premium calculation to be attempted.
    • See the "Get Perils Deductibles Allowed" method on our page describing the new business application support methods for how to get a list of the possible peril codes and the deductibles allowed for each peril.
  • disqualifyingConditionsAgreement - must be included and verify that the risk meets our eligibility requirements to get a price indication
    • version - Must match the latest version of our eligibility requirements.
    • riskMeetsEligibilityRequirements - True if the risk meets our requirements and false otherwise.
    • See the "Get Disqualifiers" method on our page describing the new business application support methods for how to get the current list of eligibility requirements that must pass for CATcoverage to consider insuring it.

Personal lines - Create a new business application and get a price indication.

  • In the Postman collection, open the request named "Get Price Indication - PERS - new app".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
    • Depending on the risk data entered, this response can take between about 15 to 60 seconds to return.
      • This may seem slow, but we're running several 3rd-party data collection and rate/premium calculation methods on the backend call to give you the best possible price through our insurers for the given risk.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data that includes the following items of special interest:
    • ApplicationId - used to identify this application in later API requests and responses
    • cost
      • totalCost - the resulting total cost to obtain a policy (premium plus any fees or taxes)
      • lineItems - the list of line items that make up the totalCost (premium, each fee, each tax)
    • status.status
      • statusCode - identifies the current status of the overall new business application
      • statusMessage - identifies any reasons provided for the current status (for example, if the premium could not be calculated this will contain the general reason why)
    • status.eligibility
      • isEligible - false when the given risk cannot be accepted by any of our several product offerings, or if eligibility could not be determined because risk data is not yet complete enough
      • problems - if isEligible is false, a list of any problems describing why eligibility hasn't passed
    • status.sections - identifies the specific status for each section of information in the application, along with any message related to that status

Personal price indication - request description

  • risk - an object with information identifying the risk data, address, and limits to be insured.
    • buildingData
      • buildingDescription is required and should be unique for all buildings in the same application.
      • floodZone can be specified to match a flood zone determination result from a mortgagee requiring flood insurance.
      • buildingReplacementCostValue should be provided to ensure it is accurate.
        • This is different than the limit of insurance for the building, provided by limits.building.
      • All other properties here are optional and we will attempt to auto-fill them.
        • If we can't fill in a value, the result will include a message identifying what must be provided to obtain a price indication.
        • To get a list of the values allowed for these properties, see our new business application support methods page.
    • address
      • address contains the physical location of the building. It cannot be a PO Box or mailing address different than the physical location of the property to be insured.
      • copyToMailingAddress can be set to true if the same address can be used for the insured's mailing address for CATcoverage correspondence.
      • limits - the requested limits of insurance for the building.
      • Note that the buildingData.buildingReplacementCostValue is different than this building limit.
  • perilsDeductibles - contains the perils selected to be insured for this risk.
    • At least one peril must be selected.
    • The deductibleCode value must be provided for the premium calculation to be attempted.
    • See the "Get Perils Deductibles Allowed" method on our page describing the new business application support methods for how to get a list of the possible peril codes and the deductibles allowed for each peril.
  • disqualifyingConditionsAgreement - must be included and verify that the risk meets our eligibility requirements to get a price indication
    • version - Must match the latest version of our eligibility requirements.
    • riskMeetsEligibilityRequirements - True if the risk meets our requirements and false otherwise.
    • See the "Get Disqualifiers" method on our page describing the new business application support methods for how to get the current list of eligibility requirements that must pass for CATcoverage to consider insuring it.

About the disqualifying conditions agreement.

The insured and/or the producer representing them must be able to affirm that all of our disqualifying conditions do not apply to the risk being presented.
We will not provide coverage for any of these conditions. Any claims made where we determine these conditions were not actually met may be denied and coverage canceled.

These conditions may change.
We have provided a method for obtaining the current full list of disqualifying conditions, based on the requested perils and risk location.
The response data is formatted to make it fairly easy to present the disqualifying conditions to your users within your own user interface.

See the "Get Disqualifiers" method on our page describing the new business application support methods for how to get the current list of eligibility requirements that must pass for CATcoverage to consider insuring it.

If you don't get a price in the response the first time...

Sometimes the risk information cannot all be obtained automatically, and you may need to include extra information before CATcoverage can obtain a price indication.
If the response doesn't include a premium in the response.cost.totalCost property (or if it's $0), look at the response.status object, and at the sections listed there, to identify the problem.
You can call the price indication multiple times to update an existing new business application information as needed.
See the following section for details about doing that.

Update an existing new business application and recalculate the price indication.

To update the material information for an existing new business application, you basically call price-indication as described above, except for a couple differences in the request data.

  • Include the applicationId so CATcoverage knows which application should be updated.
  • Only include data points that should be updated. Anything left out will not be updated.
  • To update commercial buildings (in the risks list of the request), include the id (a GUID value) for the building to be updated. Not providing this will result in a new building being added to the application.

See the following example requests of this in our Postman collection:

  • Get Price Indication - COMM - update existing app
  • Get Price Indication - COMM - update existing app - no updates
  • Get Price Indication - PERS - update existing app
  • Get Price Indication - PERS - update existing app - no updates

Step 2 - Update insured contact information

Allows setting the contact information for the insured.

Update insured information

  • In the Postman collection, open the request named "Update Insured".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data.
    • The updated insured contact information can be verified in this result.

Update insured - request description

  • name
    • For commercial lines:
      • firstNameOrCompanyName contains the company name.
    • For personal lines:
      • firstNameOrCompanyName contains the first name.
      • lastName contains the last name.
  • mailingAddress
    • Contains the mailing address for contacting the insured via regular mail (physical location or PO box).
    • If a previous request flagged to copy the physical risk location to the mailing address, this can be left out and the existing insured address will be kept.
  • phoneNumbers
    • Contains a list of contact phone numbers for the insured.
    • Each number contains:
      • contactType
        • value can be either "Mobile" or "Home"
      • number - a U.S. phone number
        • formatted either as all digits or with dashes ("801-239-5577" and "8012395577" both work)
  • email
    • The primary email address for contacting the insured.
  • sendPaymentReceiptToEmail
    • If true, the insured will get an emailed payment receipt after the application is approved and payment has been made for the new policy.

Step 3 - Complete mortgagee information

If insurance is not being required by a mortgagee, there is no requirement to provide this.
If no mortgagee will be provided, you must indicate this by calling the no-mortgagees method.
Use the POST, PUT, DELETE, GET methods to manage mortgagees when required.

Flag no mortgagees

  • In the Postman collection, open the request named "Flag No Mortgagees".
  • Note that there is no request body, so also no need to set a request content type header.
    • The applicationId for the affected insurance application is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response.
  • You can call the "Get Application" method to review the updated mortgagee information if necessary. (See that step below for details.)

Add mortgagee

  • In the Postman collection, open the request named "Add Mortgagee".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the added mortgagee information.

Add mortgagee - request description

  • name - a name to identify the mortgagee.
  • includeSuccessorOrAssigns - false unless provided and set to true - will include this label along with the name in any correspondence.
  • includeInterests - false unless provided and set to true - will include this label along with the name in any correspondence.
  • loanNumber
  • positionNumber - the position of this mortgagee within the mortgagee list - must be unique in the new business application.
  • isMortgageeBilled - true if the mortgagee should be billed for renewals.
  • isMortgageeRequired - true if the mortgagee requires the requested insurance for a loan.
  • address - the mailing address components for correspondence to the mortgagee.
  • email - the primary email address to contact the mortgagee.
  • sendPaymentReceiptToMortgagee - if true, the mortgagee will receive an email receipt when payment is received for the new policy after obtaining underwriter approval.

Update mortgagee

  • In the Postman collection, open the request named "Update Mortgagee".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the added mortgagee information.

Update mortgagee - request description

This is the same as the "Add Mortgagee" request above. See that for details.

Delete mortgagee

  • In the Postman collection, open the request named "Delete Mortgagee".
  • Note that there is no request body, so also no need to set a request content type header.
    • The mortgageeGuid for the mortgagee to be removed is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response.
  • You can call the "Get Application" method to review the updated mortgagee information if necessary. (See that step below for details.)

Get all mortgagees for a new business application

  • In the Postman collection, open the request named "Get Mortgagees".
  • Note that there is no request body, so also no need to set a request content type header.
    • The applicationId for the affected insurance application is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the list of all mortgagees saved on the new business application.

Step 4 - Update the requested inception date (optional)

Allows setting the requested inception date to a future date.
By default, the inception date will be the date the application is paid in full for the new policy (after approval by underwriting).

The inception date must be set within a valid date range.
See the "Get Valid Inception Date Boundaries" method on our page describing the new business application support methods for how to get the current valid date range.

Update the requested inception date

  • In the Postman collection, open the request named "Update Requested Inception Date".
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response.
  • You can call the "Get Application" method to review the updated mortgagee information if necessary. (See that step below for details.)

Update requested inception date - request description

  • requestedInceptionDate
    • A date without any time element, formatted as "yyyy-MM-dd".
    • Example: "2022-08-14"

Step 5 - Get required disclosures

Some acknowledgements will need to be verified and affirmed in order to submit to underwriting.
These acknowledgements, or the text presented by them, are subject to change.
We have provided a method for identifying which disclosures apply for a given new business application, which includes the specific current text for each that must be acknowledged and affirmed and whether it has been flagged as acknowledged.
The result is returned in a format to help make it easy to present to end-users in your own system for acknowledgement.

Any required acknowledgements for a given new business application must be affirmed by the insured or the producer representing them before coverage will be considered.
Any claims made where we determine these conditions were not actually met may be denied and coverage canceled.

Get the required disclosures

  • In the Postman collection, open the request named "Get Required Disclosures".
  • Note that there is no request body, so also no need to set a request content type header.
    • The applicationId for the affected insurance application is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with a list of texts to be acknowledged for coverage consideration.
  • Each item in the response data list includes:
    • an ID to uniquely identify the text item
    • a title for identifying the text to end-users
    • the text to be presented (includes some simple HTML tags)
    • a flag for whether the item has already been acknowledged

Step 6 - Submit the application for underwriting consideration

Submits a completed new business application to underwriting for acceptance consideration.

Acknowledgements will need to be verified and affirmed in order to submit to underwriting.
For more details, see the Get required disclosures step above.

In many cases, the submission response will immediately provide a status of approved or declined.
In other cases, a human underwriter will need to review the risk. The submit status will show as submitted and you may need to check back at intervals (up to 48 hours) until the status is changed to either approved, declined, or hold.
See the following step about checking the status after submission for more details.

Submit an application for underwriting consideration

  • In the Postman collection, open the request named "Submit To Underwriting".
    • Note that the applicationId for the affected insurance application is provided in the request URL.
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application.
  • Review the response data to determine the updated status of the application.
    • In the response object, look at status.status.statusCode.
    • See the following step about checking the status after submission for more details.

Submit application to underwriting - request description

  • acknowledgements
    • A list of the acknowledgements to be affirmed with this submission.
    • See the Get required disclosures step above for more details about obtaining the required acknowledgements for a specific new business application.
    • Each item in this list must include:
      • textId
        • The unique ID for the acknowledgment.
      • isAcknowledged
        • Should be true if the insured or the producer representing them confirms that the text was acknowledged.
        • These will all need to be marked as true for the application to be submitted for underwriting consideration.
  • signature
    • signatureText
      • A text representation of the signing party's signature to confirm that the acknowledgement statements are true.
    • signingParty
      • Identifies whose signature this is.
      • Possible values:
        • Insured
        • Producer

Step 7 - Get application status after submission

In many cases, the response after submitting an application to underwriting will immediately provide a status of approved or declined.
In other cases, a human underwriter will need to review the risk. The submit status will show as submitted and you may need to check back at intervals for up to 48 hours until the status is changed to either approved, declined, or hold.

A new business application object will contain the current status in this property: status.status.statusCode

The current new business application data can be found in the underwriting submission response or also in the response from fetching a given new business application (see the "Get Application" step below).

New Business Application Statuses

Below are the possible statuses for a new business insurance application on CATcoverage (related to submission and underwriting approval).

The statusMessage for a new business application will not provide the reason for the status being Declined or Hold.
That information must be obtained by querying the policy notes and reading the last ones added by the underwriter.
See the "Get Policy Notes" method on our page describing the new business application support methods for how to query policy notes for a new business application.

  • Submitted
    • The application is submitted for underwriter approval. A human underwriter will review and respond within 48 hours.
  • Approved
    • Underwriting has approved the request for coverage. No coverage is yet provided until payment is made in full and all required signatures have been collected. Most approvals are valid for 45 days.
  • ApprovedPaid
    • The application has been approved and paid for. Any required signatures must be collected for a policy to be issued.
  • Declined
    • Underwriting has declined the request for coverage.
    • Query the policy notes to get the underwriting message about why coverage was declined. See the next subsection for more details.
  • Hold
    • Underwriting is requesting more information before making a decision.
    • Query the policy notes to get the message from underwriting requesting more information. See the next subsection for more details.
  • Expired Approval
    • The application was formerly approved, but the approval has since expired.
  • Archived
    • The application was unsubmitted and subsequently archived due to inactivity.
  • Promoted
    • The new business application was paid for and promoted to a policy in effect.
    • This can include policies still awaiting the inception date as well as policies since canceled or expired.
  • New, In The Works, Review
    • Any of these statuses mean the application is in-the-works and not submitted for underwriter consideration.

If application status is Hold...

If the application status changes to "Hold", the underwriter is either asking for more information or may also be asking to resubmit with coverage changes before acceptance can be granted.
You will need to query the policy notes for the given application to see what was requested by the underwriter.
See the "Get Policy Notes" method on our page describing the new business application support methods for how to query policy notes for a new business application.

If the underwriter has asked a question and simply needs a response or documents uploaded, you can use the resubmit method to respond with your own note and attached documents.
See the next step about resubmitting for more details.

If the underwriter has asked you to make changes to the application, you will need to unsubmit the application to make any changes except the following:

  • Insured contact information
  • Mortgagee information
  • Flood zone (personal lines only) See the next step about unsubmitting for more details.

Step 8 - Unsubmit or resubmit if necessary

Submitting to underwriting is managed via 3 methods:

  • sign-and-submit-to-underwriting
    • If you have an application in the works (not already submitted for consideration), use this method to submit the application for underwriting consideration.
    • Even if the application has been submitted and unsubmitted previously, this method should be used to submit to underwriting.
  • unsubmit
    • To remove an application from underwriter consideration (usually to make material changes and submit again), use this method.
    • You can submit the application again to underwriting with the sign-and-submit-to-underwriting method.
  • resubmit
    • If you have an application already submitted for underwriting consideration and need to provide requested information (a message or attached document), use this method to respond to underwriting.
    • Not used to submit an application in the works to underwriting.
    • The application must already be in a submitted state to call this method (submitted, hold, approved).

Unsubmit an application from underwriter consideration

  • In the Postman collection, open the request named "Unsubmit From Underwriting".
  • Note that there is no request body, so also no need to set a request content type header.
    • The applicationId for the affected insurance application is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data.
    • The resulting status.status.statusCode should show as new or in-the-works now, instead of one of the submitted status codes.
    • See the "Get application status after submission" step above for a list of these statuses.

Resubmit an application to underwriter to underwriting

  • In the Postman collection, open the request named "Resubmit to Underwriting".
    • Note that the applicationId for the affected insurance application is provided in the request URL.
  • Select the Headers tab and verify that a header is included with key "Content-Type" and value "application/json".
  • Select the Body tab.
    • Verify that "raw" is selected.
    • Look over the body request data to familiarize yourself with it.
      • See the request description below for more details about this.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data.
    • The resulting status.status.statusCode should still be one of the submitted status codes.
    • See the "Get application status after submission" step above for a list of these statuses.

Resubmit an application - request description

  • note
    • The text message of the note you are sending back to underwriting.
  • document
    • Optional - if no document is to be attached, leave this out completely or set the name to an empty string and data to null.
    • If a document should be attached, include the following here:
      • name
        • The name for the document.
      • data
        • The document data (4 MB size maximum in base 64 encoding for text or raw binary data).

Step 9 - Get application (as needed)

You can fetch all existing information about a new business application to check the current status, premium, risk data, or contact information.

Get all application data

  • In the Postman collection, open the request named "Get Application".
  • Note that there is no request body, so also no need to set a request content type header.
    • The applicationId for the affected insurance application is provided in the request URL.
  • Click the blue Send button to execute the method.
  • When the method completes, you should receive a 200 (OK) response with the resulting new business application data.